.TH lha_buildapp 1 "23 May 2012" "TrueCL Commands"

.SH NAME
lha_buildapp \- Build or Change Application Configuration

.SH SYNOPSIS
.TS
l l.
clreq	\fB-A|--application\fP \fIX\fP [\fB--startscript\fP \fIS\fP] [\fB--stopscript\fP \fIS\fP]
	[\fB--starttimeout\fP \fIN\fP] [\fB--stoptimeout\fP \fIN\fP] [\fB--nodes\fP \fI[+|-]node,...\fP]
	[\fB--prefernode\fP \fINode|$$ORDERED|$$ROUND_ROBIN| ...
	    $$LEAST_APPS|$$LEAST_LOAD|$$MOST_MEMORY\f{]
	[\fB--vg\fP \fI[+|-]vg,...\fP] [\fB--storage\fP \fIdrbd1|drbd8|nfs|shared|raw\fP]
	[\fB--consistency\fP \fInormal|force\fP] [\fB--topology\fP \fIT\fP] [\fB--syncrate\fP \fIN\fP]
	[\fB--fs\fP \fI[+|-]mntpnt[:vg:lv:fstype:opts],...\fP] [\fB--lmigrate|--nolmigrate\fP]
	[\fB--ip\fP \fI[+|-]ip:network[:netmask=y,broadcast=z]\fP] [\fB-timeout\fP \fIN\fP]
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--lwidth\fP \fIN\fP] [\fB--validate\fP [\fB--forcevalidate\fP]] [\fP--vmtype\fP \fIX\fP]
	[\fB--migratescript\fP \fIS\fP] [\fB--migratetransport\fP \fIS\fP] [\fB--migratetimeout\fP \fIN\fP]
or:
clreq	\fB-A|--application\fP \fIX\fP \fB--fs\fP \fI+/mntpnt:resize=NNN\fP
or:
clreq	\fB-A|--application\fP \fIX\fP \fB--lv\fP \fI+VG:LV:resize=NNN\fP
.TE

.SH DESCRIPTION
The \fIlha_buildapp(1)\fP command is used to build new applications, and change existing
ones. It takes a large range of parameters, some of which must be specified and used during the
application build before others. 

\fBIT IS RECOMMENDED THAT THE ADMINISTRATORS GUIDE IS REFERRED TO BEFORE USING THIS COMMAND.\fP

The utility can also be used to change the size of exisiting file systems or logical volumes, 
even whilst the application is running. It does this using the relevant volume manager and 
file system utilities and commands to perform the resize. Depending on the storage in use this
may take some considerable time to run.

The only parameter that always must be present is the one that specifies the application. Not all
applications require all parameters to be defined, and many of the parameters are not strictly
necessary unless the application being defined has certain characteristics.

As with all TrueCL commands the commands can be run on any node. However it often makes sense
when initially defining the application to mount he file systems being used on one of the nodes
and define the application from there - this is because it allows TrueCL to clean to file system
types and mount options automatically rather than you having to provide them.

.SH ARGUMENTS
.TP 8
--application
This is the name of the application to create or update. Multiple \fIlha_buildapp(1)\fP
commands can be used to used to define the application, so the command will obviously
work if the application is defined already.

If this is a new application there are two parameters that are expected to be used
to define the storage during the initial application configuration that takes place:

.TP
--storage
This indicates the type of storage that the application is using. An application can only
use one type of storage, though different applications can use different types of storage
in the same cluster if you wish.

There are currently 4 types of storage types defined:

.RS 8
.TP 8
drbd1
This is deprecated now; though should still work. It is a Linux-only solution
suitable for storage replication over IP between two nodes. Each node has a 
local copy of the data; no expensive dual-attached storage is necessary.
.TP
drbd8
If you wish to use replicated storage between two Linux nodes then this is
the preferred option. It is based on drbd 8.x [see www.drbd.org for details].
Since this is a replicated solution no expensive dual-attached storage is
necessary.
.TP
nfs
If an application wishes to make use of nfs to store its data then this type
should be used. It differs from the other storage types because it does not
get deactivated/unmounted when an application is stopped, or activated/mounted
when the application is started. This allows it to be present on multiple nodes at the 
same time.
.TP
shared
This should be used whenever the storage in question is the same physical storage
mapped to the nodes in the cluster. TrueCL will activate/deactivate access to this
storage on a per-node basis depending on which node is running the application at
any one time.
.TP
raw
This type of storage is used when the storage is not being managed as part of a
volume manager. The main use for this type of storage is to allow mulitple nodes
to access the storage at the same time without having to use a clustered volume
manager. 

At present this is a good choice for providing storage for virtual machine-based
applications that require to support live migration.
.RE

\fBThe storage type is not related to the Volume Manager in use\fP. For example in 
Linux LVM is used for all the above storage types.

.TP
--vg
This defines the volume groups that the application will use. Only one application can
use a particular volume group name across the cluster - this will be checked and the
change rejected if it does already exist elsewhere.

This can be a comma-separated list and the volume groups can [if you wish] be active on the
current machine where the application is being created for. 

The list can be preceded with a '+' - and in this instance the list of volume groups 
given is added to any existing list [duplicates being automatically removed]. If the list 
beings with a '-' it will remove the specified list of volume groups defined for the
application if they are currently defined.

When a volume group is removed from the application configuration any associated file systems
are also removed. If the application is currently running those file systems will be 
un-mounted and the disk group deactivated, though no data which actually be deleted.

.TP
--nodes
This is a list of nodes that the application should be made available to work on. The "-" prefix
can be used to remove the specified nodes from the list of existing nodes, and the "+" to add them.
As usual with a "-" or "+" prefix the lis of nodes specified becomes the new list of nodes for the
application replacing all existing nodes.

Please note that this can be a regular expression to match multiple nodes; for example if toy
wished to add nodes "node01", "node02" and "node03" to the existing node list the following
value could be used: "+node0[123]".

.TP
--startscript
Indicates the script to run when the application is to be started on the node. Please note that
this is run as root once all storage for the application is active and so can reference
the storage used for the application if necessary.

.TP
--stopscript
The script used to stop the application. This is run as root and is run whilst all the storage
is active. Once this script completes all remaining processes using the storage associated
with the application will be killed off to ensure the storage can be deactivated where 
appropriate.

       $::_SPC [--fs [+|-]mntpnt[:vg:lv:fstype:opts],...] [--topology T]
.TP
--ip
This allows IP address manipulation for the application. It takes a single argument in the
form:

.TS
l.
[+|-]IP:network[:netmask=y,broadcast=z]
.TE

The IP address can be a name or dotted quad - IPv6 will be supported soon - and the 
network is the name of a defined topology in the cluster. The netmask and broadcast options
default suitably if not specified.

Without the optional '+' or '-' then the IP address specified replaces any existing 
IP configuration for the application - beware if the application is currently running since
the changes will occur immediately!

The '+' means that the IP details are added to any existing entries, whilst the '-' means that
matching entries are removed from the configuration of the application.

.TP
--fs
This is used to define, add or remove file systems from the application definition. The
first character indicates the type of action. If prefixed by a '+' it indicates this is an
additional file system, (or changes to an existing file system), whilst when prefixed with
'-' if indicates the file system specified should be removed.

If not prefixed by a '+' or a '-' this indicates that the file system is to replace ALL
existing definitions of file systems for the package.

If the file system is already mounted locally then just the mount point can be given,
otherwise some additional attributes must be specified, colon separated, from the 
mount point:

.RS 4
.TP 4
vg
The name of the volume group/disk group where this file system is hosted from.
.TP
lv
The name of the logical volume/volume on which this file system resides.
.TP
fstype
The file system type (must be one of the supported file system types).
.TP
options
The mount options for the file system.
.RE

.TP
--lv
If a logical volume does not include a file system on it, then this option can be used to 
define it as part of the application. The format of the entry is "vg:lv" - where vg is the name
of the volume group/disk group for the logical volume in question. 

As with other multiple objects that can be defined for the application, the item in question
should be prefixed with '+' to add it to existing item, '-' to remove it from the list. If the
item is not prefixed by anything it replaces all definitions of this type for the application.

When using raw storage the format of the item is different, typically being:

--lv NONE:name(machineA=path,machineB=path)

This allows the same device to use different paths on different hosts. 

.TP
--starttimeout
Overrides the default timeout (60 seconds) for waiting for the application to start. This
is defined in seconds. It should definitely be long enough for the application to start - even
on a busy host. Setting this too short will result in the application start-up being terminated
with an error.

.TP
--stoptimeout
Overrides the default timoout (60 seconds) for the application stop script to complete. Setting
this too short will cause the application processes to be forcefully terminated; which often
might not be a good thing. Hence this should be long enough to ensure the application can be
shutdown cleanly when possible.

.TP
--migratescript
This is a script which is run on a node hosting a virtual machine based application that is
due to be live-migrated to another node.  It runs on the node currently hosting the
application. Please note that this is not typically needed since the \fIlha_migrateapp(1)\fP
command handles most aspects of the migration transparently.

.TP
--migratetimeout
Defaults to 60 seconds and should be long enought to ensure that the application can
migrate in this time. If not then the migration will be aborted if possible, probably leaving it
still live on the original node.

.TP
--migratetransport
This is a string which is used by the necessary virtualisation type for the virtual machine
to determine the method of communication between nodes when performing a live migration.
For some virtual machine types this is not necessary to be specified, whilst it is mandatory for
others.

For example if using "virsh" with basic (unencrypted) tcp transport the argument might be:

--migratetransport "tcp(port=22)"

For "ssh" instead it might be:

--migratetransport "ssh(user=root,nc=/usr/local/bin/netcat)"

.TP
--validate
Perform application validatation. This must be done when the application has first been
defined or any changes are made to an existing application. This double checks all possible
settings and if suitable marks the application is being defined correctly allowing it to be 
started, stoppped and where applicable; migrated.

.TP
--forcevalidate
If the application already exists and is up and running this option will probably be 
necessary instad of the standard \fB--validate\fP. This option allows certain checks that 
might fail or not run correctly since the application is up to pass and allow the
application to be validated.

.TP
--lmigrate|--nolmigrate
If the application is a virtual machine, this argumnet can be used to flag the application
as being suitable for live migration or not. If suitable for live migration the \fIlha_migrateapp(1)\fP
command can be used to move virtual machine between nodes without downtime when all necessary 
preconditions for such migration are in place.

.TP
--vmtype
Indicates the application in question is actually a virtual machine. In such cases it is not
usually necessary to define application start and stop scripts. The TrueCL software will start/stop
the virtual machine as part of the application start-up and shutdown.

.TP
--force
If any nodes that should be part of the cluster are not currently contactable via 
the request daemons then any attempt to use \fIlha_buildapp(1)\fP will fail by default.
To force through the change without being able to contact all nodes use this argument.

It should be noted that this is not recommended since it can lead to inconsistent cluster
configurations across the nodes. 
.TP
--timeout
The amount of time to wait for certain responses to requests that are 
necessary for the application to be stopped.  If this is not specified it will
default to 10 [seconds].
.TP
--debug
Run the application modification in 'debug' mode - might produce significant levels 
of output to the standard output device, most of which is only useful for
developers.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of application modification. This is the recommended flag if
the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during attempted change of the 
application status.

.SH OUTPUT
None of the output modes generates anything really lengthy. Typically this 
command completes in less than a second and so feedback via the \fB--verbose\fP
option is not typically needed.

.SH EXIT CODES
If the application status is changed as expected, a return code of '0' will be given, 
indicating success. Otherwise a failure is indicated with a return code of '1'.
If a failure does occur then a suitable error message should be shown on the
standard output device too.

.SH FILES
The utility uses the cluster request daemons to handle all changes. Hence any 
changes, problems or errors will be found in the log files for that
daemon, available on each node in the cluster. 

.TS
l l.
clreqd.log	Standard log file for messages.
clreqd.stdout	Will contain any standard output text for the application.
clreqd.stderr	Will contain any error output text for the application.
.TE

.SH NOTES
Remember all settings only exist whilst the cluster is running. If the cluster is
stopped and restarted any changes will be lost and settings will return to default.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2010, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR clreq(1),
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_build(1),
.BR lha_destroyapp(1),
.BR lha_migrateapp(1),
.BR lha_startapp(1).
.BR lha_stopapp(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

